feat(nodes): add Docker API backend by ArshSSandhu · Pull Request #394 · mieweb/opensource-server

ArshSSandhu · 2026-07-08T00:22:52Z

Summary

Closes #375.

This PR adds support for Docker-backed nodes by introducing a new DockerApi implementation that follows the existing Node API contract used by ProxmoxApi and DummyApi.

Changes include:

Added DockerApi using Docker Engine's native HTTP API through axios
Added support for Docker host formats:
- unix:///var/run/docker.sock
- tcp://host:2375
- http://...
- https://...
Updated Node.api() to dispatch to DockerApi when nodeType === "docker"
Added provider-neutral API access checks through node.hasApiAccess()
Updated container provisioning node selection to use Node.provisionableWhere(...)
Added nodeType support to node API serialization, create, and update routes
Updated the node form UI to support Proxmox, Docker, and dummy nodes
Allowed Docker host values such as unix:///var/run/docker.sock in the frontend form

Related Issue

Closes #375

Testing

Tested locally with the following checks:

Ran backend syntax checks successfully:

node --check create-a-container/models/node.js
node --check create-a-container/utils/docker-api.js
node --check create-a-container/utils/container-status.js
node --check create-a-container/routers/api/v1/containers.js
node --check create-a-container/routers/api/v1/nodes.js

Ran frontend type-check successfully:
```
npm run client:type-check
```

Ran whitespace checks successfully:

git diff --check
git diff --cached --check

Tested DockerApi directly against local Docker using:
```
unix:///var/run/docker.sock
```
Verified direct Docker lifecycle flow:
- Pulled nginx:latest
- Created a Docker container
- Started the container
- Checked running status
- Deleted the test container

Verified the UI can create a Docker node with:

Name: local-docker
Node type: Docker
Docker host: unix:///var/run/docker.sock

Attempted full UI container creation with nginx:latest. The job selected the Docker node and Docker image path correctly, but failed with:
```
connect ENOENT /var/run/docker.sock
```
This appears to be a local runtime/socket-mount limitation because the Manager runtime does not currently have the host Docker socket mounted. The DockerApi itself was verified successfully through the direct lifecycle test above.

Screenshots

Docker node form

Docker node created

Breaking Changes

None known.

Notes

Full end-to-end Docker provisioning from the UI requires the Manager runtime to have access to the configured Docker host. For local socket usage, /var/run/docker.sock must be mounted or otherwise reachable from the process running Manager.

runleveldev

The UI displays "Creds missing" for Docker nodes

Running our default templates fail since they use SystemD. Similar to how Proxmox checks for "application containers" and make the nessecary adjustments, this needs to check for "system containers" and make the nessacary adjustments (such as setting privileged: true)

7a542e3b9e12   ghcr.io/mieweb/opensource-server/base:latest            "/sbin/init"             19 seconds ago   Exited (255) 17 seconds ago                hollow-urban-otter

runleveldev · 2026-07-09T14:31:58Z

+  async createLxc(node, options = {}) {
+    if (!this.lastPulledImage) {
+      throw new Error('No Docker image has been pulled for this create operation');
+    }


This is an unnecessary check. Images might be cached for example.

Fixed in b652af3 — fix(docker): allow cached images during create.

@ArshSSandhu please drop the commit that fixed this. I misunderstood the behavior of the image parsing and given the existing behavior this.lastPulledImage should always be set during this operation and docker image caching would already apply properly based on image reference.

ArshSSandhu · 2026-07-16T01:51:39Z

The Docker credential badge was fixed in 15ffc48 — fix(nodes): handle Docker credential badge.

The systemd/default template handling was fixed in e3e9465 — fix(docker): support system containers.

I pushed the requested review fixes as separate commits so each item is easier to inspect.

Testing run:

backend node --check commands
frontend npm run type-check from create-a-container/client
git diff --check

I replied on the individual threads with the commit that addresses each item. I left the Docker real container ID thread unresolved because Containers.containerId is currently INTEGER.UNSIGNED, so using Docker’s real string/hash ID needs a schema decision.

runleveldev · 2026-07-16T13:17:39Z

+            },
+          ]
+        : [];
+    } catch (err) {


This is swallowing all errors, not just errors indicating that the nodes is not part of a swarm. This could cause a swarm-included node to improperly present as a not swarm node due to communication failures rather than throwing as expected.

runleveldev · 2026-07-16T13:24:33Z

+  async createLxc(node, options = {}) {
+    if (!this.lastPulledImage) {
+      throw new Error('No Docker image has been pulled for this create operation');
+    }


@ArshSSandhu please drop the commit that fixed this. I misunderstood the behavior of the image parsing and given the existing behavior this.lastPulledImage should always be set during this operation and docker image caching would already apply properly based on image reference.

runleveldev · 2026-07-16T13:25:35Z

+    image.includes('/base:') ||
+    image.includes('/base@') ||
+    image.endsWith('/base')


This is a bad hueristic. Stick with what you've got based on the entrypoint.

runleveldev · 2026-07-16T13:28:13Z

+function validateNodeInput({ nodeType, apiUrl }) {
+  const type = normalizeNodeType(nodeType);
+
+  if (!['proxmox', 'docker', 'dummy'].includes(type)) {


Make sure the OpenAPI spec is updated as well.

ArshSSandhu and others added 2 commits July 7, 2026 20:11

feat(nodes): add Docker API backend

a24e99f

Merge branch 'main' into 375-docker-node-api

c80e307

runleveldev self-requested a review July 8, 2026 15:32

runleveldev requested changes Jul 9, 2026

View reviewed changes

ArshSSandhu added 3 commits July 13, 2026 12:24

fix(nodes): handle Docker credential badge

15ffc48

fix(nodes): keep provisionable query operators in model

c7fd90f

fix(docker): use org label namespace

b5de6b8

runleveldev mentioned this pull request Jul 13, 2026

create-a-container: MVC manifesto + phases 0-1 (test scaffolding, apikeys pilot migration) #405

Open

ArshSSandhu and others added 13 commits July 13, 2026 13:39

fix(docker): require node api url

05b05eb

fix(docker): validate Docker host format

25437b6

fix(nodes): reject invalid Docker hosts

9afd241

fix(docker): remove invalid node fallbacks

c28a689

feat(docker): list swarm nodes when available

eb4601a

feat(docker): read swarm node network info

ff8f675

docs(docker): explain image cache handling

5e42932

fix(docker): allow cached images during create

b652af3

fix(docker): support system containers

e3e9465

docs(docker): explain task wait no-op

4237179

fix(docker): reuse network inspect result

dcde503

fix(nodes): remove node form formatting noise

593a4eb

Merge branch 'main' into 375-docker-node-api

d72ce06

runleveldev requested changes Jul 16, 2026

View reviewed changes

Uh oh!

Conversation

ArshSSandhu commented Jul 8, 2026

Summary

Related Issue

Testing

Screenshots

Docker node form

Docker node created

Breaking Changes

Notes

Uh oh!

runleveldev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

runleveldev Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

ArshSSandhu Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

runleveldev Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ArshSSandhu commented Jul 16, 2026

Uh oh!

runleveldev Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

runleveldev Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

runleveldev Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

runleveldev Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants